.so ../bk-macros
.TH "bk smerge" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.SH NAME
bk smerge \- smart text-based 3-way file merge
.SH SYNOPSIS
.\"
.\".Bc bk smerge [\-23efghns] [
.B bk smerge
.[B] \-2efghn
.[OPTreq] \-A n
.[OPTreq] \-a n
.\".Bc ] [
.\".OPTreq \-R r
.\".B ] 
.OPTreq \-l local
.OPTreq \-r remote
.ARG file
.SH DESCRIPTION
.LP
The
.B bk smerge
command compares the three versions of the file and 
identifies all changes by either the local or the remote version of the 
file compared to the greatest common ancestor (gca).  These
groups of changes are known as conflict regions and are bounded by a
line that is identical in all three versions at the beginning of
the conflict region and at the end of the conflict region.  For each
region, one or more of the automerge algorithms (see below) are run
to see if the changes may be merged automatically.
.LP
The
.B bk smerge
command does not use the traditional
.BR diff3 (1)
merge.
There are a number of heuristics in the default enabled merge
algorithms which help determine regions which are safe to automerge.
These can simplify and resolve many conflict regions that can not
be resolved in the traditional
.BR diff3 (1)
merge.  Please note, smerge can
only be run on SCCS files.
.LP
In some scripts users may want to call smerge directly.  If so, an example
for usage is:
.DS
bk smerge -g -l1.661 -r1.660.1.4 slib.c > slib.c.merged
.DE
where 1.661 is the local revision and 1.660.1.4 is the remote
revision, slib.c is the file name and slib.c.merged is the file to
which merge output is redirected.
.LP
The string for the local or remote versions of the file can be
expressed in the form "rev+includes-excludes" where rev is a normal
revision number like "1.661" and includes and excludes are a comma
separated list if revisions to include or exclude from the base
revision. (The include and/or exclude lists can be omitted if they are
empty.)  
.SH "MERGE ALGORITHMS"
.LP
Each of the automerge algorithms is described below.  Currently,
all of these are run by default, but that may change in the future.
Any mix of these may be selectively enabled or disabled.
.TP
.B 1. Merge identical changes made by both sides
If both the local and the remote files have made an identical change
to the GCA, then this function will resolve the region and replace it
with the new text.
.tp
.B 2. Merge when only one side changes
This code finds conflict regions where only the local or the remote
version has made any changes.  In this case the conflict is resolved
and the side that made changes is kept.  This is the traditional
.BR diff3 (1)
type automerge algorithm.
.tp
.B 3. Merge adjacent, non-overlapping modifications on both sides
This code attempts to find a conflict consisting of a text
substitution in both the local and remote versions of the file.  A
substitution is a line or group of lines that is deleted and then
replaced with zero or more lines.  If there is a conflict region that
contains lines substituted in the local file that are unmodified in the
remote and there are lines substituted in the remote file that are
unmodified in the local file, then a merge of the two substitutions is
performed.
.sp
Here is an example of a conflict region (in the
.Q \-g
output format)
where this algorithm will successfully resolve the conflict.
.DS
\&<<<<<<< local slib.c 1.642.1.6 vs 1.645
	sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
-	assert(sc->tree);
- 	sccs_sdelta(sc, sc->tree, file);
+	assert(HASGRAPH(sc));
+	sccs_sdelta(sc, sccs_ino(sc), file);
\&<<<<<<< remote slib.c 1.642.1.6 vs 1.642.2.1
-	sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
+	sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
	assert(sc->tree);
	sccs_sdelta(sc, sc->tree, file);
>>>>>>>
.DE
The block after the resolve will be:
.DS
	sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
	assert(HASGRAPH(sc));
	sccs_sdelta(sc, sccs_ino(sc), file);
.DE
Multiple substitutions are not yet handled.
.tp
.B 4. Merge identical changes at the start of a conflict
This code recognizes one or more lines at the beginning the local and
remote versions of a conflict region that are identical.  If there
is a block of lines that are identical then the region is split into
two regions with the identical lines in a region by themselves.  This
block will later be resolved by algorithm #1.
.tp
.B 5. Merge identical changes at the end of a conflict
This is similar to algorithm #4, except it looks for identical lines on both
sides at the end of the conflict region.
.tp
.B 6. Merge identical deletions made by both sides
If both the local and remote version of a region have deleted the
same non-zero block of lines at the end of the region, then split the
region into two with the deletions in a separate region.  The
deletions will then get autoresolved.
.LP
When a conflict regions is identified, then the enabled algorithms are run
on the block repeatedly until the block is resolved or no further
progress is made.
.LP
Default conflict output format is as follows:
.DS
\&<<<<<<< gca slib.c 1.642.1.6
	sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
	assert(sc->tree);
	sccs_sdelta(sc, sc->tree, file);
\&<<<<<<< local slib.c 1.645
	sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, s->proj);
	assert(HASGRAPH(sc));
	sccs_sdelta(sc, sccs_ino(sc), file);
\&<<<<<<< remote slib.c 1.642.2.1
	sc = sccs_init(file, INIT_NOCKSUM|INIT_SAVEPROJ, p);
	assert(sc->tree);
	sccs_sdelta(sc, sc->tree, file);
>>>>>>>
.DE
Lines with "<<<<<<<" indicate the file the conflict region is from in
the form: <<<<<<< 
.ARG label
.ARG file
.ARG revision
followed by the conflict lines from that file.  The end of the conflict region
is indicated by ">>>>>>>".
Examples of conflict output can be viewed by using the
.Q \-e
option.
.SH OPTIONS
.TP \-A\*<n\*>n
.B \-2
Enable the 2 way output format (like
.BR diff3 (1)).
.tp
.B \-g
Enable 'gca' output format that shows the local and
remote files like a unified diff between the GCA and that file.
This is the recommended output format, but not the default because
it confuses people the first time they see it.
.tp
.B \-n
Enable the 'newonly' output format.  (like
.Q \-2
except it marks added lines).
.tp
.B \-e
Print examples of all 4 output formats from 
.BR "bk smerge" .
.tp
.OPTreq \-a n
Enable merge functions
.ARG n ,
where 
.ARG n
is a comma separated list of automerge algorithms specified by number.
.Qreq \-a all
will enable all automerge algorithms.   
Use 
.Q bk smerge \-h
to find the algorithms enabled by default.
.tp
.OPTreq \-A n
Disable merge functions
.ARG n ,
where
.ARG n
is a comma separated list of automerge algorithms specified by number.
.Qreq \-A all
will turn off all automerging.
.tp
.B \-f
Enable fdiff output.  (Used internally by 
.Bc bk fm3tool
)
.\".tp
.\".B \-s
.\"Show sequence numbers in output
.tp
.B \-h
Display automerge algorithms by number that are enabled by default.
If used in conjunction with
.Q \-a
or
.QR \-A ,
asterisks denote enabled algorithms.
.\".tp
.\".OPTreq \-r range
.\"When given a range of the format 'start..end' it limits the output to
.\"just the sequence numbers after (not including) 'start' and before (not 
.\"including) 'end'.  start or end can be omitted to go to the end of the file.
.SH EXIT STATUS
.B bk smerge
returns exit status:
.TP
0
if there were no conflicts
.tp
1
if there were conflicts
.tp
2
if an error occurred
.SH "SEE ALSO"
.BR diff3 (1),
.SA resolve
.SA resolving
.SA merge
.SH CATEGORY
.B Utility
